feat(Runtime): Add Rollout Percentage functionality #81

chiraag918 · 2025-07-28T00:07:24Z

✨ Feature: Rollout Percentage with Persistent Bucketing & Release Awareness

📌 What this PR adds

This PR introduces client-side rollout percentage support for CodePush updates, with the following features:

Rollout-based user bucketing
- If a CodePush update contains a rollout percentage (e.g., 30), each device is deterministically assigned to a 0–99 bucket using a stable hash of its unique ID.
- The update will only be applied if the device falls within the allowed rollout percentage.
Persistent rollout decisions per update
- Once a device is bucketed for a given update (packageHash and rollout), the decision is cached locally using AsyncStorage.
- This avoids re-bucketing or re-evaluation on every app start, ensuring consistent behavior for the same update across app sessions.
Rollout re-evaluation on update change
- If the update label or the rollout value changes, the rollout decision is recalculated and the cache is reset automatically.

🧪 Behavior Summary

Scenario	Behavior
Same update label & rollout	Cached decision is reused
New label or new rollout value	Re-bucketing is triggered
Device outside rollout bucket	Update is skipped

✅ Why this is useful

Enables gradual rollout strategies at the client level..
Offers full control over rollout and update logic, useful in large-scale deployments or A/B testing.

🙏 Request to Maintainers

Dear maintainers, I'd love your feedback on this PR. If this feature aligns with your goals for the package, I kindly request a review and merge.

The logic is isolated and does not interfere with existing behavior if rollout.
If there’s anything you’d like me to revise, optimize, or test further, I’m happy to update the PR accordingly.

Thank you for maintaining this awesome package! 🙌

Let me know if you'd like me to add:

Documentation to the README
A usage example for the new feature

floydkim · 2025-07-30T09:26:38Z

Hello! @chiraag918
Thank you for implementing such a great feature.

Although I haven’t received any direct requests for it yet, I believe there are definitely use cases where the progressive rollout feature will be useful.
It’s been a few days since you submitted the PR, but I’ve been reviewing the code whenever I get the chance.

--

About the feature

The idea of using the device ID for bucketing is very interesting!
However, as far as I understand, the rollout percentage directly corresponds to the bucket number.
This means that devices in the smaller-numbered buckets will always be part of the early rollout, while those in larger-numbered buckets will always receive updates later.
In other words, certain user groups could repeatedly experience unstable releases.

I’ve been thinking about how we could add a bit of randomness to this.
One idea is to generate the hash not only from the deviceId, but also by including the package’s label or packageHash values.
What do you think? Would you be open to accepting this idea?

--

About the `disabled` flag

I’m not entirely convinced about the need for the disabled flag.
In what use cases would it be necessary?

Also, I couldn’t find the corresponding implementation in the diff. (unless I missed it)
I’d prefer that it not be included in the diff until I better understand its usefulness. 🙏
If it turns out to be needed, it would be better to implement it in a separate PR.

chiraag918 · 2025-08-02T22:39:59Z

Hello @floydkim

First of all, thank you so much for taking the time to review my contribution. I really appreciate your thoughtful feedback! 🙏

Latest Commit Changes - followed your suggestion to include packageHash
Based on your suggestion, I’ve updated the implementation in the latest commit to make the bucketing system more random. Instead of just using the device ID, I’ve now included the packageHash in the input used for generating the bucket. I’ve also added a random number multiplier factor to further reduce the chances of the same devices consistently falling into the same rollout phase. Hopefully, this approach makes the rollout behaviour fairer and more resilient.

About the disabled flag
Regarding the disabled flag, my apologies for the confusion. It's actually not a new flag or feature. The rollout logic simply respects the existing enabled flag from the CodePush metadata. If it’s set to false, the progressive rollout flow doesn’t execute. I've updated the PR description as well to avoid confusion.

About testing
I've tested my contribution by patching @bravemobile/react-native-code-push package on one of my react native apps. Is there a defined way of testing that is expected by the team for the contribution to be accepted?

Thanks again for the valuable feedback! Please let me know if you'd like me to make any further changes.

floydkim · 2025-08-03T12:21:25Z

@chiraag918
Thank you for accepting my idea 😄

I noticed that you added a random factor along with the package hash.
However, this means that when a user deletes and reinstalls the app, they could end up in a different bucket, and there’s a chance they won’t be able to return to the app version they had before deleting it.
I believe this has both pros and cons. Personally, I think it appealing that our library could be distinguished by ensuring users maintain the same experience with the same update.

I also think that adding a random factor somewhat diminishes the meaning of using the device ID and package hash. With the random factor added, doesn’t the outcome essentially become the same as just using Math.random()? 🤔

If the random factor were removed, I believe deterministic bucketing could be achieved for the same device and the same CodePush update.

(If my previous comment using the phrase “a bit of randomness” caused any confusion, I sincerely apologize. 🙏)

chiraag918 · 2025-08-03T12:55:50Z

@floydkim true, if the user were to uninstall & reinstall the app, the previous decision can get changed depending on the random factor 😅. So in that case, keeping device ID and packageHash would solve for this use case right? I added the random factor to make it a bit more random. I can remove the random multiplier. Any other suggestions or thoughts?

(No worries, these conversations helps me with understanding these corner cases, thanks 😀)

floydkim · 2025-08-03T14:37:07Z

@chiraag918
I think it would be better to remove the random factor and only use the device ID and package hash.

If the need ever arises, we could later add an option to make the bucketing completely random. :)

chiraag918 · 2025-08-03T16:51:02Z

@floydkim I've removed the random factor multiplier in my recent commit. Request you to please review the PR once. Thank you.

floydkim

Hi @chiraag918 !
Sorry for the delay.

I reviewed the code thoroughly and had some questions, so I’ve asked them.
Please respond when you have time. 😄

Once I understand your answers, I’m thinking of merging the PR first and then making the changes myself, including some minor coding style tweaks.
What do you think about it?
I want to reduce the back-and-forth on feedback and move quickly toward releasing the feature.

floydkim · 2025-07-28T05:03:13Z

typings/react-native-code-push.d.ts

+     * @param deploymentKey The deployment key to use to query the CodePush server for an update.
+     *
     * @param handleBinaryVersionMismatchCallback An optional callback for handling target binary version mismatch
     */
-    function checkForUpdate(handleBinaryVersionMismatchCallback?: HandleBinaryVersionMismatchCallback): Promise<RemotePackage | null>;
+    function checkForUpdate(deploymentKey?: string, handleBinaryVersionMismatchCallback?: HandleBinaryVersionMismatchCallback): Promise<RemotePackage | null>;


Since deploymentKey has been deprecated, it should not be added back.
Was this change intentional?

Sorry took this change from the package code that I was using to test my changes. Have reverted this change.

floydkim · 2025-07-28T05:04:46Z

CodePush.js

+    if(remotePackage?.skipRollout){
+      syncStatusChangeCallback(CodePush.SyncStatus.UNKNOWN_ERROR);
+      return CodePush.SyncStatus.UNKNOWN_ERROR;
+    }


I think this status should be CODEPUSH_SKIPPED.

Updated this

floydkim · 2025-07-30T08:43:50Z

CodePush.js

-    const remotePackage = { ...update, ...PackageMixins.remote() };
+    const remotePackage = { ...PackageMixins.remote(), ...update };


Is it necessary to change the order of the spread operation?

Hmmm I don't think so, initially I guess it was taking default rollback value as 100, hence, had changed the order, so the rollout value comes from the remote fetched config. Now I've removed the fallback value as suggested in one of the other other PR comments. Reverted this change.

floydkim · 2025-07-30T08:47:20Z

CodePush.js

+    // Rollout filtering
+    const shouldApply = await shouldApplyCodePushUpdate(remotePackage, nativeConfig.clientUniqueId, sharedCodePushOptions?.onRolloutSkipped);
+
+    if(!shouldApply && !remotePackage.enabled)


enabled property is not exists.

Yes my bad, actually I wanted to know when the package wasn't enabled and based on that I skip handling the rollout part. This is already handed in the above if condition where if update is null/undef it skips the else block inside which rollout logic is present. So !remotePackage.enabled is no longer required.

floydkim · 2025-07-30T09:20:34Z

CodePush.js

+  if(prevRolloutCacheKey)
+    await RolloutStorage.removeItem(prevRolloutCacheKey);
+
+  await RolloutStorage.setItem(ROLLOUT_CACHE_KEY, rolloutKey);


It seems possible to implement without adding ROLLOUT_CACHE_KEY..
I will take a look while refactoring the code.

Okay pls do share once you refactor.

floydkim · 2025-07-31T05:03:03Z

CodePush.js

+}
+
+function getRolloutKey(label, rollout) {
+  return `${ROLLOUT_CACHE_PREFIX}${label}_rollout_${rollout ?? 'full'}`;


When rollout parameter is 100, returns ${ROLLOUT_CACHE_PREFIX}${label}_rollout_${100},
and when it’s undefined, returns ${ROLLOUT_CACHE_PREFIX}${label}_rollout_${'full'}.

I don’t think the two return values need to be different, and it seems fine to just use 100 directly in the key.

Have made this change.

floydkim · 2025-08-10T08:13:38Z

CodePush.js

+    if(remotePackage?.skipRollout){
+      syncStatusChangeCallback(CodePush.SyncStatus.UNKNOWN_ERROR);
+      return CodePush.SyncStatus.UNKNOWN_ERROR;
+    }


Is there a particular reason why we need to distinguish the state where it’s skipped because it’s not within the rollout range?

In apps that used the UP_TO_DATE state to inform users that "the app is up to date", code changes will be necessary due to the addition of this new state.
(If not using the rollout feature, no changes would be needed, of course.)

There may be operational or management reasons, but I think it’s possible to collect that information through the onRolloutSkipped callback.

Created a different state to maintain a different state for codepush skipped scenario for better readability during dev. Instead what would you suggest to keep this state as?

In my opinion, if the update is not the rollout target, it could be treated the same as the UP_TO_DATE state.

Distinguishing between the two cases can be helpful for understanding the code and flow.
But from an end user’s perspective, they are essentially the same and app should present a message like 'The app is already up to date.'
For developers using our library, I feel it might be more natural to handle this with just the UP_TO_DATE state.
This way, they do not have to account for both states in their if statements to display the same message.

Okay makes sense, have changed this state to UP_TO_DATE and have removed refs for CODEPUSH_SKIPPED.

floydkim · 2025-08-10T08:17:33Z

android/app/src/main/java/com/microsoft/codepush/react/RolloutStorageModule.java

+import com.facebook.react.bridge.ReactMethod;
+import com.facebook.react.bridge.Promise;
+
+public class RolloutStorageModule extends ReactContextBaseJavaModule {


The SettingsManager already handles interactions with SharedPreference.
Was the reason you added a new module instead to separate concerns?

I didn't really want to touch the other modules, hence, added this module, but lmk, if I should instead stick to using SettingsManager?

Oh, no. I was just curious about the reason.
For now, since I’m not familiar with the implementation of SettingsManager, I like the way you implemented.

Okay great!

floydkim · 2025-08-10T08:24:45Z

cli/commands/releaseCommand/index.js

@@ -16,6 +16,7 @@ program.command('release')
    .option('-j, --js-bundle-name <string>', 'JS bundle file name (default-ios: "main.jsbundle" / default-android: "index.android.bundle")')
    .option('-m, --mandatory <bool>', 'make the release to be mandatory', parseBoolean, false)
    .option('--enable <bool>', 'make the release to be enabled', parseBoolean, true)
+    .option('--rollout <number>', 'rollout percentage (0-100)', parseFloat, 100)


Personally, I think it would be better not to add the rollout property when the rollout feature is not used, so that the JSON data doesn’t grow unnecessarily.

Yes done removed.

I think there was a misunderstanding because I didn’t explain clearly. Sorry.
What I meant was that undefined is fine as the default value, not that the CLI option should be removed. 😭

If the user doesn’t pass the --rollout option when calling the release command, I’d prefer that the release history object not include the rollout property when it’s created.

Oops my bad. I've added this cli cmd option with the default value argument removed.

floydkim · 2025-08-10T08:36:30Z

ios/CodePush/RolloutStorage.h

+RCT_EXTERN_METHOD(setItem:(NSString *)key value:(NSString *)value)
+RCT_EXTERN_METHOD(getItem:(NSString *)key resolver:(RCTPromiseResolveBlock)resolve rejecter:(RCTPromiseRejectBlock)reject)
+RCT_EXTERN_METHOD(removeItem:(NSString *)key)


I’m not sure if the RCT_EXPORT_METHOD macro is needed in the header file as well.

From what I can find, it doesn’t seem to be commonly declared in headers.

https://github.com/search?type=code&q=RCT_EXPORT_METHOD+language%3AObjective-C+path%3A*.h

https://github.com/search?type=code&q=RCT_EXPORT_METHOD+language%3AObjective-C+path%3A*.m

https://github.com/search?type=code&q=RCT_EXPORT_METHOD+language%3AObjective-C%2B%2B+path%3A*.mm

Hmm afaik its a good practice to have a header file to have function prototype declarations, hence, added it. Should I remove it?

I’m not an iOS/Objective-C expert, so I'd like to follow either the library’s current implementation style or approaches used in other libraries.

In the CodePush.h and CodePush.m files, the RCT_EXPORT_METHOD macro appears only in the .m file, and the header doesn’t declare these methods.
(I’m not certain if this is because the macro removes the need for function prototype declarations.. 🤔)

From my understanding, RCT_EXPORT_METHOD need not be included in the header files. The ones that you shared seems to be like react bridging header files to bridge objective-c & swift code, since, swift doesn't yet support exposing native methods to React JS like how we do in objective-c.

Similarly RCT_EXTERN_METHOD is similar to RCT_EXPORT_METHOD but used with swift files. Including/Excluding it in our case doesn't make a difference is what I suppose.

Yes you're right, in CodePush.h and CodePush.m files, the RCT_EXPORT_METHOD macro appears only in the .m file, since its not required to duplicate the macro in both the files.

But considering both 1 & 2, I've removed RCT_EXTERN_METHOD from the .h file and RCT_EXPORT_METHOD only is used in the .m file, as this is what RN suggests: https://reactnative.dev/docs/0.73/native-modules-ios#create-custom-native-module-files

Oh, I confused RCT_EXTERN_MODULE with RCT_EXPORT_MODULE.
(And also RCT_EXTERN_METHOD and RCT_EXPORT_METHOD)

I wasn’t familiar with RCT_EXTERN_MODULE, but as you mentioned, it’s used to register implementations in Swift.
Thanks for sharing your knowledge.

Anyway, the final code you’ve updated looks good 👍

Okay thanks

chiraag918 · 2025-08-11T21:40:25Z

Sorry was little busy with work, hence the delay. I've addressed the PR comments. I think 3 comments, I wasn't sure, need your suggestion on it. Pls go through them and lmk, will take action. Thank you!!!

floydkim · 2025-08-12T15:13:41Z

@chiraag918
Thank you for responding to the review quickly.
I have left some comments, please check them 👍

chiraag918 · 2025-08-13T22:12:22Z

@floydkim Addressed the last few open comments. Pls check it out and lmk if any other changes are required. Thanks for your time & support! 🤝

floydkim · 2025-08-14T05:22:14Z

@chiraag918 Thank you for your great work.
I think we can merge this PR now, and then I will do some testing and minor code style refactoring.
(I'll open a PR and mention you so you can read through the changes.)

I'll slightly update the PR title for the GitHub release notes and then merge it.
Thank you for bearing with the communication overhead and for your understanding.

chiraag918 · 2025-08-14T09:20:49Z

@floydkim Thank you so much for your time, effort, for guiding this through and accepting my contribution. I really appreciate the collaboration. Please feel free to reach out if anything comes up during your testing or refactoring, I’ll be happy to help with any issues 😁

*[ft] add rollout feat

eeeb4e0

floydkim self-requested a review July 28, 2025 05:09

*[m] add packageHash & random number to bucket prediction logic

5d27109

*[m] rm random multiplier

1bd6756

floydkim reviewed Aug 10, 2025

View reviewed changes

chiraag918 added 2 commits August 12, 2025 02:52

*[m] address PR comments

1ba36c3

*[m] address PR comments

63e6c01

chiraag918 requested a review from floydkim August 11, 2025 21:40

*[m] address PR comments - refactor rollout.h

512609e

floydkim changed the title *[ft] Add Rollout Percentage functionality feat(Runtime): Add Rollout Percentage functionality Aug 14, 2025

floydkim approved these changes Aug 14, 2025

View reviewed changes

floydkim merged commit c5ecdfe into Soomgo-Mobile:master Aug 14, 2025
1 check passed

floydkim mentioned this pull request Aug 17, 2025

feat(Runtime): Allow rollout cancellation and simplify decision logic #83

Merged

		const remotePackage = { ...update, ...PackageMixins.remote() };
		const remotePackage = { ...PackageMixins.remote(), ...update };

feat(Runtime): Add Rollout Percentage functionality #81

feat(Runtime): Add Rollout Percentage functionality #81

Uh oh!

Conversation

chiraag918 commented Jul 28, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

✨ Feature: Rollout Percentage with Persistent Bucketing & Release Awareness

📌 What this PR adds

🧪 Behavior Summary

✅ Why this is useful

🙏 Request to Maintainers

Uh oh!

floydkim commented Jul 30, 2025

About the feature

About the disabled flag

Uh oh!

chiraag918 commented Aug 2, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

floydkim commented Aug 3, 2025

Uh oh!

chiraag918 commented Aug 3, 2025

Uh oh!

floydkim commented Aug 3, 2025

Uh oh!

chiraag918 commented Aug 3, 2025

Uh oh!

floydkim left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

chiraag918 Aug 11, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

floydkim Aug 12, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

chiraag918 commented Jul 28, 2025 •

edited

Loading

About the `disabled` flag

chiraag918 commented Aug 2, 2025 •

edited

Loading

chiraag918 Aug 11, 2025 •

edited

Loading

floydkim Aug 12, 2025 •

edited

Loading

floydkim Aug 14, 2025 •

edited

Loading